Many people are familiar with Mail Merge feature in Microsoft Word. It is used when you want to send a set of documents that has the same kind of information, but personalized for each recipient. For example: you want to send a gathering invitation to all members of IT division. You can send the invitation to all members using the same template but personalized for each recipient. This feature is also supported in WebTextEditor.

You can enable this feature instantly by setting the EnableMailMerge property available in MailMergeSettings. The collection of recipients can be specified as data bound collection or custom collection. When data bound collection is used, the datasource control id can be specified as DataSourceID property.

<ISWebTextEditor:WebTextEditor ID="WebTextEditor1" runat="server" Height="80%" 
Width="100%" DataMember="DefaultView" DataSourceID="AccessDataSource1">

When custom collection is used, the collection can be added to Recipients collection.

private void BindCustomCollection() 
{ 
   List<ISEmployee> employees = new List<ISEmployee>(); 
   
   ISEmployee emp = new ISEmployee(); 
   emp.EmployeeID = 1; 
   emp.FirstName = "Nancy"; 
   emp.LastName = "Davolio"; 
   emp.Address = "Bridge Street"; 
   emp.City = "London"; 
   emp.Country = "UK"; 
   employees.Add(emp); 

   emp = new ISEmployee(); 
   emp.EmployeeID = 2; 
   emp.FirstName = "Andrew"; 
   emp.LastName = "Fuller"; 
   emp.Address = "Wood Street"; 
   emp.City = "Washington"; 
   emp.Country = "USA"; 
   employees.Add(emp); 

   WebTextEditor1.MailMergeSettings.Recipients = employees; 
}

When the collection of recipients are ready, you need to specify the labels. Labels are used to indicate parts of the content that will be replaced with the related data in the data context. You can specify as many labels as needed in the template. Each label contain the following properties:

• Label (mandatory): specifies the text used as label.
• DataMember (mandatory): specifies the field or property in data context that will be used to replace the label text.
• FormatString (optional): specifies the format string of the label. This property can be specified if you want to have a specific format on dates or numbers.

The collection of labels can be added in MailMergeSettings >> Labels property.

The labels will be added to Insert Merge Label dropdown in main toolbar. Users can easily select an item from this command in main toolbar and it will be added to editor. Users will not be able to modify the labels manually in the editor window.

Users can preview the mail merge result in Preview tab. The labels will be automatically replaced with the related data in the data context and users can navigate through the data using the previous and next commands in toolbar.

Users can also send the mail using Send Mail Merge command. Some related properties that need to be configured are:

• EmailField: specifies the field or property in data context that contains email data.
• From: specifies the email of sender.
• IsHTML: specifies whether or not the email should be sent as HTML format.
• MailPriority: specifies the priority status of the email.
• SMTP: specifies the SMTP server.
• SubjectExpression: specifies the subject of the email. Labels can be included as the value of this property and they will automatically be replaced with related data when the email is sent.

WebTextEditor provides various server-side events that will be invoked when the emails are about to be sent. If you have specific scenarios that need custom actions, these events can be used to implement those actions.

• OnBeforeSendMail event is invoked the emails are sent.
• OnMailMerge event is invoked when each email is merged with the related data from data context.
• OnMailMergeCompleted event is invoked when all emails have been merged with the related data from the data context.
• OnSendMail event is invoked when each email is about to be sent.
• OnSendMailCompleted event is invoked after all emails are sent.

If you set AutomaticSendMail property to False, you can specify your own configuration and send mail process in OnSendMail event.

protected void WebTextEditor1_SendMail(object sender, ISNet.WebUI.WebTextEditor.WebTextEditorSendMailArgs e) 
{ 
   //specify your own configuration 
   e.Cancel = true; // needed to cancel built-in send mail process 
}

After all emails are sent, you might need to display specific custom status in WebTextEditor or perform other custom actions in client-side. In this case, you can use OnSendMailCompleted client-side event. In this event, the failed emails data will also be passed as parameters. So, in cases where emails are failed to be sent to recipients, you can perform custom actions to handle the scenario.

<script type="text/javascript"> 
   function OnSendMailCompleted(controlId, failed, failedEmails) 
   { 
      var editor = ISGetObject(controlId); 

      if (failed > 0) 
      { 
	 // you can implement custom action to handle this scenario 
      } 
      else 
 	 editor.SetStatus("All emails are successfully sent at " + new Date() + "."); 
} 
</script>

If you have feedback regarding this feature, feel free to drop a comment or create a new discussion in our new Forum.